

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="zh" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="zh" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>optuna.study &mdash; Optuna 1.4.0 文档</title>
  

  
  
    <link rel="shortcut icon" href="../../_static/favicon.ico"/>
  
  
  

  
  <script type="text/javascript" src="../../_static/js/modernizr.min.js"></script>
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
        <script src="../../_static/jquery.js"></script>
        <script src="../../_static/underscore.js"></script>
        <script src="../../_static/doctools.js"></script>
        <script src="../../_static/language_data.js"></script>
        <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
    
    <script type="text/javascript" src="../../_static/js/theme.js"></script>

    

  
  <link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="../../_static/css/custom.css" type="text/css" />
    <link rel="index" title="索引" href="../../genindex.html" />
    <link rel="search" title="搜索" href="../../search.html" /> 
</head>

<body class="wy-body-for-nav">

   
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
          

          
            <a href="../../index.html" class="icon icon-home"> Optuna
          

          
          </a>

          
            
            
              <div class="version">
                1.4.0
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <p class="caption"><span class="caption-text">目录</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../installation.html">安装</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../tutorial/index.html">教程</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../reference/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../faq.html">常见问题</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../../index.html">Optuna</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="../../index.html">Docs</a> &raquo;</li>
        
          <li><a href="../index.html">模块代码</a> &raquo;</li>
        
      <li>optuna.study</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <h1>optuna.study 源代码</h1><div class="highlight"><pre>
<span></span><span class="kn">import</span> <span class="nn">collections</span>
<span class="kn">import</span> <span class="nn">copy</span>
<span class="kn">import</span> <span class="nn">datetime</span>
<span class="kn">import</span> <span class="nn">gc</span>
<span class="kn">import</span> <span class="nn">math</span>
<span class="kn">import</span> <span class="nn">threading</span>
<span class="kn">import</span> <span class="nn">warnings</span>

<span class="kn">import</span> <span class="nn">joblib</span>
<span class="kn">from</span> <span class="nn">joblib</span> <span class="kn">import</span> <span class="n">delayed</span>
<span class="kn">from</span> <span class="nn">joblib</span> <span class="kn">import</span> <span class="n">Parallel</span>

<span class="kn">from</span> <span class="nn">optuna._experimental</span> <span class="kn">import</span> <span class="n">experimental</span>
<span class="kn">from</span> <span class="nn">optuna._imports</span> <span class="kn">import</span> <span class="n">try_import</span>
<span class="kn">from</span> <span class="nn">optuna._study_direction</span> <span class="kn">import</span> <span class="n">StudyDirection</span>
<span class="kn">from</span> <span class="nn">optuna._study_summary</span> <span class="kn">import</span> <span class="n">StudySummary</span>  <span class="c1"># NOQA</span>
<span class="kn">from</span> <span class="nn">optuna</span> <span class="kn">import</span> <span class="n">exceptions</span>
<span class="kn">from</span> <span class="nn">optuna</span> <span class="kn">import</span> <span class="n">logging</span>
<span class="kn">from</span> <span class="nn">optuna</span> <span class="kn">import</span> <span class="n">progress_bar</span> <span class="k">as</span> <span class="n">pbar_module</span>
<span class="kn">from</span> <span class="nn">optuna</span> <span class="kn">import</span> <span class="n">pruners</span>
<span class="kn">from</span> <span class="nn">optuna</span> <span class="kn">import</span> <span class="n">samplers</span>
<span class="kn">from</span> <span class="nn">optuna</span> <span class="kn">import</span> <span class="n">storages</span>
<span class="kn">from</span> <span class="nn">optuna</span> <span class="kn">import</span> <span class="n">trial</span> <span class="k">as</span> <span class="n">trial_module</span>
<span class="kn">from</span> <span class="nn">optuna.trial</span> <span class="kn">import</span> <span class="n">FrozenTrial</span>
<span class="kn">from</span> <span class="nn">optuna.trial</span> <span class="kn">import</span> <span class="n">TrialState</span>
<span class="kn">from</span> <span class="nn">optuna</span> <span class="kn">import</span> <span class="n">type_checking</span>

<span class="k">if</span> <span class="n">type_checking</span><span class="o">.</span><span class="n">TYPE_CHECKING</span><span class="p">:</span>
    <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Any</span>  <span class="c1"># NOQA</span>
    <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Callable</span>
    <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Dict</span>  <span class="c1"># NOQA</span>
    <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">List</span>  <span class="c1"># NOQA</span>
    <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Optional</span>  <span class="c1"># NOQA</span>
    <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Set</span>  <span class="c1"># NOQA</span>
    <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Tuple</span>  <span class="c1"># NOQA</span>
    <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Type</span>  <span class="c1"># NOQA</span>
    <span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Union</span>  <span class="c1"># NOQA</span>

    <span class="kn">from</span> <span class="nn">optuna.distributions</span> <span class="kn">import</span> <span class="n">BaseDistribution</span>  <span class="c1"># NOQA</span>

    <span class="n">ObjectiveFuncType</span> <span class="o">=</span> <span class="n">Callable</span><span class="p">[[</span><span class="n">trial_module</span><span class="o">.</span><span class="n">Trial</span><span class="p">],</span> <span class="nb">float</span><span class="p">]</span>

<span class="k">with</span> <span class="n">try_import</span><span class="p">()</span> <span class="k">as</span> <span class="n">_pandas_imports</span><span class="p">:</span>
    <span class="c1"># `trials_dataframe` is disabled if pandas is not available.</span>
    <span class="kn">import</span> <span class="nn">pandas</span> <span class="k">as</span> <span class="nn">pd</span>  <span class="c1"># NOQA</span>

<span class="n">_logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">get_logger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>


<span class="k">class</span> <span class="nc">BaseStudy</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">study_id</span><span class="p">,</span> <span class="n">storage</span><span class="p">):</span>
        <span class="c1"># type: (int, storages.BaseStorage) -&gt; None</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span> <span class="o">=</span> <span class="n">study_id</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span> <span class="o">=</span> <span class="n">storage</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">best_params</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># type: () -&gt; Dict[str, Any]</span>
        <span class="sd">&quot;&quot;&quot;Return parameters of the best trial in the study.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A dictionary containing parameters of the best trial.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">best_trial</span><span class="o">.</span><span class="n">params</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">best_value</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># type: () -&gt; float</span>
        <span class="sd">&quot;&quot;&quot;Return the best objective value in the study.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A float representing the best objective value.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="n">best_value</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">best_trial</span><span class="o">.</span><span class="n">value</span>
        <span class="k">assert</span> <span class="n">best_value</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>

        <span class="k">return</span> <span class="n">best_value</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">best_trial</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># type: () -&gt; FrozenTrial</span>
        <span class="sd">&quot;&quot;&quot;Return the best trial in the study.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A :class:`~optuna.FrozenTrial` object of the best trial.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">return</span> <span class="n">copy</span><span class="o">.</span><span class="n">deepcopy</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">get_best_trial</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">))</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">direction</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># type: () -&gt; StudyDirection</span>
        <span class="sd">&quot;&quot;&quot;Return the direction of the study.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A :class:`~optuna.study.StudyDirection` object.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">get_study_direction</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">)</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">trials</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># type: () -&gt; List[FrozenTrial]</span>
        <span class="sd">&quot;&quot;&quot;Return all trials in the study.</span>

<span class="sd">        The returned trials are ordered by trial number.</span>

<span class="sd">        This is a short form of ``self.get_trials(deepcopy=True)``.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A list of :class:`~optuna.FrozenTrial` objects.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_trials</span><span class="p">()</span>

    <span class="k">def</span> <span class="nf">get_trials</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">deepcopy</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
        <span class="c1"># type: (bool) -&gt; List[FrozenTrial]</span>
        <span class="sd">&quot;&quot;&quot;Return all trials in the study.</span>

<span class="sd">        The returned trials are ordered by trial number.</span>

<span class="sd">        For library users, it&#39;s recommended to use more handy</span>
<span class="sd">        :attr:`~optuna.study.Study.trials` property to get the trials instead.</span>

<span class="sd">        Args:</span>
<span class="sd">            deepcopy:</span>
<span class="sd">                Flag to control whether to apply ``copy.deepcopy()`` to the trials.</span>
<span class="sd">                Note that if you set the flag to :obj:`False`, you shouldn&#39;t mutate</span>
<span class="sd">                any fields of the returned trial. Otherwise the internal state of</span>
<span class="sd">                the study may corrupt and unexpected behavior may happen.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A list of :class:`~optuna.FrozenTrial` objects.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">read_trials_from_remote_storage</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">)</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">get_all_trials</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">,</span> <span class="n">deepcopy</span><span class="o">=</span><span class="n">deepcopy</span><span class="p">)</span>


<div class="viewcode-block" id="Study"><a class="viewcode-back" href="../../reference/study.html#optuna.Study">[文档]</a><span class="k">class</span> <span class="nc">Study</span><span class="p">(</span><span class="n">BaseStudy</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;A study corresponds to an optimization task, i.e., a set of trials.</span>

<span class="sd">    This object provides interfaces to run a new :class:`~optuna.trial.Trial`, access trials&#39;</span>
<span class="sd">    history, set/get user-defined attributes of the study itself.</span>

<span class="sd">    Note that the direct use of this constructor is not recommended.</span>
<span class="sd">    To create and load a study, please refer to the documentation of</span>
<span class="sd">    :func:`~optuna.study.create_study` and :func:`~optuna.study.load_study` respectively.</span>

<span class="sd">    &quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
        <span class="bp">self</span><span class="p">,</span>
        <span class="n">study_name</span><span class="p">,</span>  <span class="c1"># type: str</span>
        <span class="n">storage</span><span class="p">,</span>  <span class="c1"># type: Union[str, storages.BaseStorage]</span>
        <span class="n">sampler</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: samplers.BaseSampler</span>
        <span class="n">pruner</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: pruners.BasePruner</span>
    <span class="p">):</span>
        <span class="c1"># type: (...) -&gt; None</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">study_name</span> <span class="o">=</span> <span class="n">study_name</span>
        <span class="n">storage</span> <span class="o">=</span> <span class="n">storages</span><span class="o">.</span><span class="n">get_storage</span><span class="p">(</span><span class="n">storage</span><span class="p">)</span>
        <span class="n">study_id</span> <span class="o">=</span> <span class="n">storage</span><span class="o">.</span><span class="n">get_study_id_from_name</span><span class="p">(</span><span class="n">study_name</span><span class="p">)</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">Study</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">study_id</span><span class="p">,</span> <span class="n">storage</span><span class="p">)</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">sampler</span> <span class="o">=</span> <span class="n">sampler</span> <span class="ow">or</span> <span class="n">samplers</span><span class="o">.</span><span class="n">TPESampler</span><span class="p">()</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">pruner</span> <span class="o">=</span> <span class="n">pruner</span> <span class="ow">or</span> <span class="n">pruners</span><span class="o">.</span><span class="n">MedianPruner</span><span class="p">()</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_optimize_lock</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Lock</span><span class="p">()</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_stop_flag</span> <span class="o">=</span> <span class="kc">False</span>

    <span class="k">def</span> <span class="nf">__getstate__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># type: () -&gt; Dict[Any, Any]</span>

        <span class="n">state</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__dict__</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
        <span class="k">del</span> <span class="n">state</span><span class="p">[</span><span class="s2">&quot;_optimize_lock&quot;</span><span class="p">]</span>
        <span class="k">return</span> <span class="n">state</span>

    <span class="k">def</span> <span class="nf">__setstate__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">state</span><span class="p">):</span>
        <span class="c1"># type: (Dict[Any, Any]) -&gt; None</span>

        <span class="bp">self</span><span class="o">.</span><span class="vm">__dict__</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">state</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_optimize_lock</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Lock</span><span class="p">()</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">user_attrs</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># type: () -&gt; Dict[str, Any]</span>
        <span class="sd">&quot;&quot;&quot;Return user attributes.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A dictionary containing all user attributes.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">return</span> <span class="n">copy</span><span class="o">.</span><span class="n">deepcopy</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">get_study_user_attrs</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">))</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">system_attrs</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># type: () -&gt; Dict[str, Any]</span>
        <span class="sd">&quot;&quot;&quot;Return system attributes.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A dictionary containing all system attributes.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">return</span> <span class="n">copy</span><span class="o">.</span><span class="n">deepcopy</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">get_study_system_attrs</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">))</span>

<div class="viewcode-block" id="Study.optimize"><a class="viewcode-back" href="../../reference/study.html#optuna.Study.optimize">[文档]</a>    <span class="k">def</span> <span class="nf">optimize</span><span class="p">(</span>
        <span class="bp">self</span><span class="p">,</span>
        <span class="n">func</span><span class="p">,</span>  <span class="c1"># type: ObjectiveFuncType</span>
        <span class="n">n_trials</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[int]</span>
        <span class="n">timeout</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[float]</span>
        <span class="n">n_jobs</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>  <span class="c1"># type: int</span>
        <span class="n">catch</span><span class="o">=</span><span class="p">(),</span>  <span class="c1"># type: Union[Tuple[()], Tuple[Type[Exception]]]</span>
        <span class="n">callbacks</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[List[Callable[[Study, FrozenTrial], None]]]</span>
        <span class="n">gc_after_trial</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>  <span class="c1"># type: bool</span>
        <span class="n">show_progress_bar</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>  <span class="c1"># type: bool</span>
    <span class="p">):</span>
        <span class="c1"># type: (...) -&gt; None</span>
        <span class="sd">&quot;&quot;&quot;Optimize an objective function.</span>

<span class="sd">        Optimization is done by choosing a suitable set of hyperparameter values from a given</span>
<span class="sd">        range. Uses a sampler which implements the task of value suggestion based on a specified</span>
<span class="sd">        distribution. The sampler is specified in :func:`~optuna.study.create_study` and the</span>
<span class="sd">        default choice for the sampler is TPE.</span>
<span class="sd">        See also :class:`~optuna.samplers.TPESampler` for more details on &#39;TPE&#39;.</span>

<span class="sd">        Args:</span>
<span class="sd">            func:</span>
<span class="sd">                A callable that implements objective function.</span>
<span class="sd">            n_trials:</span>
<span class="sd">                The number of trials. If this argument is set to :obj:`None`, there is no</span>
<span class="sd">                limitation on the number of trials. If :obj:`timeout` is also set to :obj:`None`,</span>
<span class="sd">                the study continues to create trials until it receives a termination signal such</span>
<span class="sd">                as Ctrl+C or SIGTERM.</span>
<span class="sd">            timeout:</span>
<span class="sd">                Stop study after the given number of second(s). If this argument is set to</span>
<span class="sd">                :obj:`None`, the study is executed without time limitation. If :obj:`n_trials` is</span>
<span class="sd">                also set to :obj:`None`, the study continues to create trials until it receives a</span>
<span class="sd">                termination signal such as Ctrl+C or SIGTERM.</span>
<span class="sd">            n_jobs:</span>
<span class="sd">                The number of parallel jobs. If this argument is set to :obj:`-1`, the number is</span>
<span class="sd">                set to CPU count.</span>
<span class="sd">            catch:</span>
<span class="sd">                A study continues to run even when a trial raises one of the exceptions specified</span>
<span class="sd">                in this argument. Default is an empty tuple, i.e. the study will stop for any</span>
<span class="sd">                exception except for :class:`~optuna.exceptions.TrialPruned`.</span>
<span class="sd">            callbacks:</span>
<span class="sd">                List of callback functions that are invoked at the end of each trial. Each function</span>
<span class="sd">                must accept two parameters with the following types in this order:</span>
<span class="sd">                :class:`~optuna.study.Study` and :class:`~optuna.FrozenTrial`.</span>
<span class="sd">            gc_after_trial:</span>
<span class="sd">                Flag to determine whether to automatically run garbage collection after each trial.</span>
<span class="sd">                Set to :obj:`True` to run the garbage collection, :obj:`False` otherwise.</span>
<span class="sd">                When it runs, it runs a full collection by internally calling :func:`gc.collect`.</span>
<span class="sd">                If you see an increase in memory consumption over several trials, try setting this</span>
<span class="sd">                flag to :obj:`True`.</span>
<span class="sd">            show_progress_bar:</span>
<span class="sd">                Flag to show progress bars or not. To disable progress bar, set this ``False``.</span>
<span class="sd">                Currently, progress bar is experimental feature and disabled</span>
<span class="sd">                when ``n_jobs`` :math:`\\ne 1`.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">catch</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span>
                <span class="s2">&quot;The catch argument is of type &#39;</span><span class="si">{}</span><span class="s2">&#39; but must be a tuple.&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
                    <span class="nb">type</span><span class="p">(</span><span class="n">catch</span><span class="p">)</span><span class="o">.</span><span class="vm">__name__</span>
                <span class="p">)</span>
            <span class="p">)</span>

        <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">_optimize_lock</span><span class="o">.</span><span class="n">acquire</span><span class="p">(</span><span class="kc">False</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">&quot;Nested invocation of `Study.optimize` method isn&#39;t allowed.&quot;</span><span class="p">)</span>

        <span class="c1"># TODO(crcrpar): Make progress bar work when n_jobs != 1.</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_progress_bar</span> <span class="o">=</span> <span class="n">pbar_module</span><span class="o">.</span><span class="n">_ProgressBar</span><span class="p">(</span>
            <span class="n">show_progress_bar</span> <span class="ow">and</span> <span class="n">n_jobs</span> <span class="o">==</span> <span class="mi">1</span><span class="p">,</span> <span class="n">n_trials</span><span class="p">,</span> <span class="n">timeout</span>
        <span class="p">)</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_stop_flag</span> <span class="o">=</span> <span class="kc">False</span>

        <span class="k">try</span><span class="p">:</span>
            <span class="k">if</span> <span class="n">n_jobs</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">_optimize_sequential</span><span class="p">(</span>
                    <span class="n">func</span><span class="p">,</span> <span class="n">n_trials</span><span class="p">,</span> <span class="n">timeout</span><span class="p">,</span> <span class="n">catch</span><span class="p">,</span> <span class="n">callbacks</span><span class="p">,</span> <span class="n">gc_after_trial</span><span class="p">,</span> <span class="kc">None</span>
                <span class="p">)</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="k">if</span> <span class="n">show_progress_bar</span><span class="p">:</span>
                    <span class="n">msg</span> <span class="o">=</span> <span class="s2">&quot;Progress bar only supports serial execution (`n_jobs=1`).&quot;</span>
                    <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
                    <span class="n">_logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>

                <span class="n">time_start</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>

                <span class="k">def</span> <span class="nf">_should_stop</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="nb">bool</span><span class="p">:</span>
                    <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_stop_flag</span><span class="p">:</span>
                        <span class="k">return</span> <span class="kc">True</span>

                    <span class="k">if</span> <span class="n">timeout</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
                        <span class="c1"># This is needed for mypy.</span>
                        <span class="n">t</span> <span class="o">=</span> <span class="n">timeout</span>  <span class="c1"># type: float</span>
                        <span class="k">return</span> <span class="p">(</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span> <span class="o">-</span> <span class="n">time_start</span><span class="p">)</span><span class="o">.</span><span class="n">total_seconds</span><span class="p">()</span> <span class="o">&gt;</span> <span class="n">t</span>

                    <span class="k">return</span> <span class="kc">False</span>

                <span class="k">if</span> <span class="n">n_trials</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
                    <span class="n">_iter</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">n_trials</span><span class="p">))</span>
                <span class="k">else</span><span class="p">:</span>
                    <span class="n">_iter</span> <span class="o">=</span> <span class="nb">iter</span><span class="p">(</span><span class="n">_should_stop</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span>

                <span class="k">with</span> <span class="n">Parallel</span><span class="p">(</span><span class="n">n_jobs</span><span class="o">=</span><span class="n">n_jobs</span><span class="p">,</span> <span class="n">prefer</span><span class="o">=</span><span class="s2">&quot;threads&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">parallel</span><span class="p">:</span>
                    <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span>
                        <span class="n">parallel</span><span class="o">.</span><span class="n">_backend</span><span class="p">,</span> <span class="n">joblib</span><span class="o">.</span><span class="n">parallel</span><span class="o">.</span><span class="n">ThreadingBackend</span>
                    <span class="p">)</span> <span class="ow">and</span> <span class="nb">isinstance</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="p">,</span> <span class="n">storages</span><span class="o">.</span><span class="n">InMemoryStorage</span><span class="p">):</span>
                        <span class="n">msg</span> <span class="o">=</span> <span class="p">(</span>
                            <span class="s2">&quot;The default storage cannot be shared by multiple processes. &quot;</span>
                            <span class="s2">&quot;Please use an RDB (RDBStorage) when you use joblib for &quot;</span>
                            <span class="s2">&quot;multi-processing. The usage of RDBStorage can be found in &quot;</span>
                            <span class="s2">&quot;https://optuna.readthedocs.io/en/stable/tutorial/rdb.html.&quot;</span>
                        <span class="p">)</span>
                        <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="ne">UserWarning</span><span class="p">)</span>
                        <span class="n">_logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>

                    <span class="n">parallel</span><span class="p">(</span>
                        <span class="n">delayed</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_reseed_and_optimize_sequential</span><span class="p">)(</span>
                            <span class="n">func</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">timeout</span><span class="p">,</span> <span class="n">catch</span><span class="p">,</span> <span class="n">callbacks</span><span class="p">,</span> <span class="n">gc_after_trial</span><span class="p">,</span> <span class="n">time_start</span><span class="p">,</span>
                        <span class="p">)</span>
                        <span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="n">_iter</span>
                    <span class="p">)</span>
        <span class="k">finally</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_optimize_lock</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_progress_bar</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
            <span class="k">del</span> <span class="bp">self</span><span class="o">.</span><span class="n">_progress_bar</span></div>

<div class="viewcode-block" id="Study.set_user_attr"><a class="viewcode-back" href="../../reference/study.html#optuna.Study.set_user_attr">[文档]</a>    <span class="k">def</span> <span class="nf">set_user_attr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
        <span class="c1"># type: (str, Any) -&gt; None</span>
        <span class="sd">&quot;&quot;&quot;Set a user attribute to the study.</span>

<span class="sd">        Args:</span>
<span class="sd">            key: A key string of the attribute.</span>
<span class="sd">            value: A value of the attribute. The value should be JSON serializable.</span>

<span class="sd">        &quot;&quot;&quot;</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_study_user_attr</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span></div>

    <span class="k">def</span> <span class="nf">set_system_attr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
        <span class="c1"># type: (str, Any) -&gt; None</span>
        <span class="sd">&quot;&quot;&quot;Set a system attribute to the study.</span>

<span class="sd">        Note that Optuna internally uses this method to save system messages. Please use</span>
<span class="sd">        :func:`~optuna.study.Study.set_user_attr` to set users&#39; attributes.</span>

<span class="sd">        Args:</span>
<span class="sd">            key: A key string of the attribute.</span>
<span class="sd">            value: A value of the attribute. The value should be JSON serializable.</span>

<span class="sd">        &quot;&quot;&quot;</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_study_system_attr</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>

<div class="viewcode-block" id="Study.trials_dataframe"><a class="viewcode-back" href="../../reference/study.html#optuna.Study.trials_dataframe">[文档]</a>    <span class="k">def</span> <span class="nf">trials_dataframe</span><span class="p">(</span>
        <span class="bp">self</span><span class="p">,</span>
        <span class="n">attrs</span><span class="o">=</span><span class="p">(</span>
            <span class="s2">&quot;number&quot;</span><span class="p">,</span>
            <span class="s2">&quot;value&quot;</span><span class="p">,</span>
            <span class="s2">&quot;datetime_start&quot;</span><span class="p">,</span>
            <span class="s2">&quot;datetime_complete&quot;</span><span class="p">,</span>
            <span class="s2">&quot;duration&quot;</span><span class="p">,</span>
            <span class="s2">&quot;params&quot;</span><span class="p">,</span>
            <span class="s2">&quot;user_attrs&quot;</span><span class="p">,</span>
            <span class="s2">&quot;system_attrs&quot;</span><span class="p">,</span>
            <span class="s2">&quot;state&quot;</span><span class="p">,</span>
        <span class="p">),</span>  <span class="c1"># type: Tuple[str, ...]</span>
        <span class="n">multi_index</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>  <span class="c1"># type: bool</span>
    <span class="p">):</span>
        <span class="c1"># type: (...) -&gt; pd.DataFrame</span>
        <span class="sd">&quot;&quot;&quot;Export trials as a pandas DataFrame_.</span>

<span class="sd">        The DataFrame_ provides various features to analyze studies. It is also useful to draw a</span>
<span class="sd">        histogram of objective values and to export trials as a CSV file.</span>
<span class="sd">        If there are no trials, an empty DataFrame_ is returned.</span>

<span class="sd">        Example:</span>

<span class="sd">            .. testcode::</span>

<span class="sd">                import optuna</span>
<span class="sd">                import pandas</span>

<span class="sd">                def objective(trial):</span>
<span class="sd">                    x = trial.suggest_uniform(&#39;x&#39;, -1, 1)</span>
<span class="sd">                    return x ** 2</span>

<span class="sd">                study = optuna.create_study()</span>
<span class="sd">                study.optimize(objective, n_trials=3)</span>

<span class="sd">                # Create a dataframe from the study.</span>
<span class="sd">                df = study.trials_dataframe()</span>
<span class="sd">                assert isinstance(df, pandas.DataFrame)</span>
<span class="sd">                assert df.shape[0] == 3  # n_trials.</span>

<span class="sd">        Args:</span>
<span class="sd">            attrs:</span>
<span class="sd">                Specifies field names of :class:`~optuna.FrozenTrial` to include them to a</span>
<span class="sd">                DataFrame of trials.</span>
<span class="sd">            multi_index:</span>
<span class="sd">                Specifies whether the returned DataFrame_ employs MultiIndex_ or not. Columns that</span>
<span class="sd">                are hierarchical by nature such as ``(params, x)`` will be flattened to</span>
<span class="sd">                ``params_x`` when set to :obj:`False`.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A pandas DataFrame_ of trials in the :class:`~optuna.study.Study`.</span>

<span class="sd">        .. _DataFrame: http://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html</span>
<span class="sd">        .. _MultiIndex: https://pandas.pydata.org/pandas-docs/stable/advanced.html</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="n">_pandas_imports</span><span class="o">.</span><span class="n">check</span><span class="p">()</span>

        <span class="n">trials</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_trials</span><span class="p">(</span><span class="n">deepcopy</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>

        <span class="c1"># If no trials, return an empty dataframe.</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="nb">len</span><span class="p">(</span><span class="n">trials</span><span class="p">):</span>
            <span class="k">return</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">()</span>

        <span class="k">assert</span> <span class="nb">all</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">trial</span><span class="p">,</span> <span class="n">FrozenTrial</span><span class="p">)</span> <span class="k">for</span> <span class="n">trial</span> <span class="ow">in</span> <span class="n">trials</span><span class="p">)</span>
        <span class="n">attrs_to_df_columns</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">OrderedDict</span><span class="p">()</span>  <span class="c1"># type: Dict[str, str]</span>
        <span class="k">for</span> <span class="n">attr</span> <span class="ow">in</span> <span class="n">attrs</span><span class="p">:</span>
            <span class="k">if</span> <span class="n">attr</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">&quot;_&quot;</span><span class="p">):</span>
                <span class="c1"># Python conventional underscores are omitted in the dataframe.</span>
                <span class="n">df_column</span> <span class="o">=</span> <span class="n">attr</span><span class="p">[</span><span class="mi">1</span><span class="p">:]</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="n">df_column</span> <span class="o">=</span> <span class="n">attr</span>
            <span class="n">attrs_to_df_columns</span><span class="p">[</span><span class="n">attr</span><span class="p">]</span> <span class="o">=</span> <span class="n">df_column</span>

        <span class="c1"># column_agg is an aggregator of column names.</span>
        <span class="c1"># Keys of column agg are attributes of `FrozenTrial` such as &#39;trial_id&#39; and &#39;params&#39;.</span>
        <span class="c1"># Values are dataframe columns such as (&#39;trial_id&#39;, &#39;&#39;) and (&#39;params&#39;, &#39;n_layers&#39;).</span>
        <span class="n">column_agg</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">defaultdict</span><span class="p">(</span><span class="nb">set</span><span class="p">)</span>  <span class="c1"># type: Dict[str, Set]</span>
        <span class="n">non_nested_attr</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>

        <span class="k">def</span> <span class="nf">_create_record_and_aggregate_column</span><span class="p">(</span><span class="n">trial</span><span class="p">):</span>
            <span class="c1"># type: (FrozenTrial) -&gt; Dict[Tuple[str, str], Any]</span>

            <span class="n">record</span> <span class="o">=</span> <span class="p">{}</span>
            <span class="k">for</span> <span class="n">attr</span><span class="p">,</span> <span class="n">df_column</span> <span class="ow">in</span> <span class="n">attrs_to_df_columns</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="n">value</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">trial</span><span class="p">,</span> <span class="n">attr</span><span class="p">)</span>
                <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">TrialState</span><span class="p">):</span>
                    <span class="c1"># Convert TrialState to str and remove the common prefix.</span>
                    <span class="n">value</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">value</span><span class="p">)</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s2">&quot;.&quot;</span><span class="p">)[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
                <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="nb">dict</span><span class="p">):</span>
                    <span class="k">for</span> <span class="n">nested_attr</span><span class="p">,</span> <span class="n">nested_value</span> <span class="ow">in</span> <span class="n">value</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                        <span class="n">record</span><span class="p">[(</span><span class="n">df_column</span><span class="p">,</span> <span class="n">nested_attr</span><span class="p">)]</span> <span class="o">=</span> <span class="n">nested_value</span>
                        <span class="n">column_agg</span><span class="p">[</span><span class="n">attr</span><span class="p">]</span><span class="o">.</span><span class="n">add</span><span class="p">((</span><span class="n">df_column</span><span class="p">,</span> <span class="n">nested_attr</span><span class="p">))</span>
                <span class="k">else</span><span class="p">:</span>
                    <span class="n">record</span><span class="p">[(</span><span class="n">df_column</span><span class="p">,</span> <span class="n">non_nested_attr</span><span class="p">)]</span> <span class="o">=</span> <span class="n">value</span>
                    <span class="n">column_agg</span><span class="p">[</span><span class="n">attr</span><span class="p">]</span><span class="o">.</span><span class="n">add</span><span class="p">((</span><span class="n">df_column</span><span class="p">,</span> <span class="n">non_nested_attr</span><span class="p">))</span>
            <span class="k">return</span> <span class="n">record</span>

        <span class="n">records</span> <span class="o">=</span> <span class="nb">list</span><span class="p">([</span><span class="n">_create_record_and_aggregate_column</span><span class="p">(</span><span class="n">trial</span><span class="p">)</span> <span class="k">for</span> <span class="n">trial</span> <span class="ow">in</span> <span class="n">trials</span><span class="p">])</span>

        <span class="n">columns</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span>
            <span class="p">(</span><span class="nb">sorted</span><span class="p">(</span><span class="n">column_agg</span><span class="p">[</span><span class="n">k</span><span class="p">])</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">attrs</span> <span class="k">if</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">column_agg</span><span class="p">),</span> <span class="p">[]</span>
        <span class="p">)</span>  <span class="c1"># type: List[Tuple[str, str]]</span>

        <span class="n">df</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">(</span><span class="n">records</span><span class="p">,</span> <span class="n">columns</span><span class="o">=</span><span class="n">pd</span><span class="o">.</span><span class="n">MultiIndex</span><span class="o">.</span><span class="n">from_tuples</span><span class="p">(</span><span class="n">columns</span><span class="p">))</span>

        <span class="k">if</span> <span class="ow">not</span> <span class="n">multi_index</span><span class="p">:</span>
            <span class="c1"># Flatten the `MultiIndex` columns where names are concatenated with underscores.</span>
            <span class="c1"># Filtering is required to omit non-nested columns avoiding unwanted trailing</span>
            <span class="c1"># underscores.</span>
            <span class="n">df</span><span class="o">.</span><span class="n">columns</span> <span class="o">=</span> <span class="p">[</span>
                <span class="s2">&quot;_&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">filter</span><span class="p">(</span><span class="k">lambda</span> <span class="n">c</span><span class="p">:</span> <span class="n">c</span><span class="p">,</span> <span class="nb">map</span><span class="p">(</span><span class="k">lambda</span> <span class="n">c</span><span class="p">:</span> <span class="nb">str</span><span class="p">(</span><span class="n">c</span><span class="p">),</span> <span class="n">col</span><span class="p">)))</span> <span class="k">for</span> <span class="n">col</span> <span class="ow">in</span> <span class="n">columns</span>
            <span class="p">]</span>

        <span class="k">return</span> <span class="n">df</span></div>

<div class="viewcode-block" id="Study.stop"><a class="viewcode-back" href="../../reference/study.html#optuna.Study.stop">[文档]</a>    <span class="nd">@experimental</span><span class="p">(</span><span class="s2">&quot;1.4.0&quot;</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">stop</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>

        <span class="sd">&quot;&quot;&quot;Exit from the current optimization loop after the running trials finish.</span>

<span class="sd">        This method lets the running :meth:`~optuna.study.Study.optimize` method return</span>
<span class="sd">        immediately after all trials which the :meth:`~optuna.study.Study.optimize` method</span>
<span class="sd">        spawned finishes.</span>
<span class="sd">        This method does not affect any behaviors of parallel or successive study processes.</span>

<span class="sd">        Raises:</span>
<span class="sd">            RuntimeError:</span>
<span class="sd">                If this method is called outside an objective function or callback.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_optimize_lock</span><span class="o">.</span><span class="n">acquire</span><span class="p">(</span><span class="kc">False</span><span class="p">):</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_optimize_lock</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
            <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span>
                <span class="s2">&quot;`Study.stop` is supposed to be invoked inside an objective function or a &quot;</span>
                <span class="s2">&quot;callback.&quot;</span>
            <span class="p">)</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_stop_flag</span> <span class="o">=</span> <span class="kc">True</span></div>

<div class="viewcode-block" id="Study.enqueue_trial"><a class="viewcode-back" href="../../reference/study.html#optuna.Study.enqueue_trial">[文档]</a>    <span class="nd">@experimental</span><span class="p">(</span><span class="s2">&quot;1.2.0&quot;</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">enqueue_trial</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">params</span><span class="p">):</span>
        <span class="c1"># type: (Dict[str, Any]) -&gt; None</span>
        <span class="sd">&quot;&quot;&quot;Enqueue a trial with given parameter values.</span>

<span class="sd">        You can fix the next sampling parameters which will be evaluated in your</span>
<span class="sd">        objective function.</span>

<span class="sd">        Example:</span>

<span class="sd">            .. testcode::</span>

<span class="sd">                import optuna</span>

<span class="sd">                def objective(trial):</span>
<span class="sd">                    x = trial.suggest_uniform(&#39;x&#39;, 0, 10)</span>
<span class="sd">                    return x ** 2</span>

<span class="sd">                study = optuna.create_study()</span>
<span class="sd">                study.enqueue_trial({&#39;x&#39;: 5})</span>
<span class="sd">                study.enqueue_trial({&#39;x&#39;: 0})</span>
<span class="sd">                study.optimize(objective, n_trials=2)</span>

<span class="sd">                assert study.trials[0].params == {&#39;x&#39;: 5}</span>
<span class="sd">                assert study.trials[1].params == {&#39;x&#39;: 0}</span>

<span class="sd">        Args:</span>
<span class="sd">            params:</span>
<span class="sd">                Parameter values to pass your objective function.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="n">system_attrs</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;fixed_params&quot;</span><span class="p">:</span> <span class="n">params</span><span class="p">}</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_append_trial</span><span class="p">(</span><span class="n">state</span><span class="o">=</span><span class="n">TrialState</span><span class="o">.</span><span class="n">WAITING</span><span class="p">,</span> <span class="n">system_attrs</span><span class="o">=</span><span class="n">system_attrs</span><span class="p">)</span></div>

    <span class="k">def</span> <span class="nf">_append_trial</span><span class="p">(</span>
        <span class="bp">self</span><span class="p">,</span>
        <span class="n">value</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[float]</span>
        <span class="n">params</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[Dict[str, Any]]</span>
        <span class="n">distributions</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[Dict[str, BaseDistribution]]</span>
        <span class="n">user_attrs</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[Dict[str, Any]]</span>
        <span class="n">system_attrs</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[Dict[str, Any]]</span>
        <span class="n">intermediate_values</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[Dict[int, float]]</span>
        <span class="n">state</span><span class="o">=</span><span class="n">TrialState</span><span class="o">.</span><span class="n">COMPLETE</span><span class="p">,</span>  <span class="c1"># type: TrialState</span>
        <span class="n">datetime_start</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[datetime.datetime]</span>
        <span class="n">datetime_complete</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[datetime.datetime]</span>
    <span class="p">):</span>
        <span class="c1"># type: (...) -&gt; int</span>

        <span class="n">params</span> <span class="o">=</span> <span class="n">params</span> <span class="ow">or</span> <span class="p">{}</span>
        <span class="n">distributions</span> <span class="o">=</span> <span class="n">distributions</span> <span class="ow">or</span> <span class="p">{}</span>
        <span class="n">user_attrs</span> <span class="o">=</span> <span class="n">user_attrs</span> <span class="ow">or</span> <span class="p">{}</span>
        <span class="n">system_attrs</span> <span class="o">=</span> <span class="n">system_attrs</span> <span class="ow">or</span> <span class="p">{}</span>
        <span class="n">intermediate_values</span> <span class="o">=</span> <span class="n">intermediate_values</span> <span class="ow">or</span> <span class="p">{}</span>
        <span class="n">datetime_start</span> <span class="o">=</span> <span class="n">datetime_start</span> <span class="ow">or</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>

        <span class="k">if</span> <span class="n">state</span><span class="o">.</span><span class="n">is_finished</span><span class="p">():</span>
            <span class="n">datetime_complete</span> <span class="o">=</span> <span class="n">datetime_complete</span> <span class="ow">or</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>

        <span class="n">trial</span> <span class="o">=</span> <span class="n">FrozenTrial</span><span class="p">(</span>
            <span class="n">number</span><span class="o">=-</span><span class="mi">1</span><span class="p">,</span>  <span class="c1"># dummy value.</span>
            <span class="n">trial_id</span><span class="o">=-</span><span class="mi">1</span><span class="p">,</span>  <span class="c1"># dummy value.</span>
            <span class="n">state</span><span class="o">=</span><span class="n">state</span><span class="p">,</span>
            <span class="n">value</span><span class="o">=</span><span class="n">value</span><span class="p">,</span>
            <span class="n">datetime_start</span><span class="o">=</span><span class="n">datetime_start</span><span class="p">,</span>
            <span class="n">datetime_complete</span><span class="o">=</span><span class="n">datetime_complete</span><span class="p">,</span>
            <span class="n">params</span><span class="o">=</span><span class="n">params</span><span class="p">,</span>
            <span class="n">distributions</span><span class="o">=</span><span class="n">distributions</span><span class="p">,</span>
            <span class="n">user_attrs</span><span class="o">=</span><span class="n">user_attrs</span><span class="p">,</span>
            <span class="n">system_attrs</span><span class="o">=</span><span class="n">system_attrs</span><span class="p">,</span>
            <span class="n">intermediate_values</span><span class="o">=</span><span class="n">intermediate_values</span><span class="p">,</span>
        <span class="p">)</span>

        <span class="n">trial</span><span class="o">.</span><span class="n">_validate</span><span class="p">()</span>

        <span class="n">trial_id</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">create_new_trial</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">,</span> <span class="n">template_trial</span><span class="o">=</span><span class="n">trial</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">trial_id</span>

    <span class="k">def</span> <span class="nf">_reseed_and_optimize_sequential</span><span class="p">(</span>
        <span class="bp">self</span><span class="p">,</span>
        <span class="n">func</span><span class="p">,</span>  <span class="c1"># type: ObjectiveFuncType</span>
        <span class="n">n_trials</span><span class="p">,</span>  <span class="c1"># type: Optional[int]</span>
        <span class="n">timeout</span><span class="p">,</span>  <span class="c1"># type: Optional[float]</span>
        <span class="n">catch</span><span class="p">,</span>  <span class="c1"># type: Union[Tuple[()], Tuple[Type[Exception]]]</span>
        <span class="n">callbacks</span><span class="p">,</span>  <span class="c1"># type: Optional[List[Callable[[Study, FrozenTrial], None]]]</span>
        <span class="n">gc_after_trial</span><span class="p">,</span>  <span class="c1"># type: bool</span>
        <span class="n">time_start</span><span class="p">,</span>  <span class="c1"># type: Optional[datetime.datetime]</span>
    <span class="p">):</span>
        <span class="c1"># type: (...) -&gt; None</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">sampler</span><span class="o">.</span><span class="n">reseed_rng</span><span class="p">()</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_optimize_sequential</span><span class="p">(</span>
            <span class="n">func</span><span class="p">,</span> <span class="n">n_trials</span><span class="p">,</span> <span class="n">timeout</span><span class="p">,</span> <span class="n">catch</span><span class="p">,</span> <span class="n">callbacks</span><span class="p">,</span> <span class="n">gc_after_trial</span><span class="p">,</span> <span class="n">time_start</span>
        <span class="p">)</span>

    <span class="k">def</span> <span class="nf">_optimize_sequential</span><span class="p">(</span>
        <span class="bp">self</span><span class="p">,</span>
        <span class="n">func</span><span class="p">,</span>  <span class="c1"># type: ObjectiveFuncType</span>
        <span class="n">n_trials</span><span class="p">,</span>  <span class="c1"># type: Optional[int]</span>
        <span class="n">timeout</span><span class="p">,</span>  <span class="c1"># type: Optional[float]</span>
        <span class="n">catch</span><span class="p">,</span>  <span class="c1"># type: Union[Tuple[()], Tuple[Type[Exception]]]</span>
        <span class="n">callbacks</span><span class="p">,</span>  <span class="c1"># type: Optional[List[Callable[[Study, FrozenTrial], None]]]</span>
        <span class="n">gc_after_trial</span><span class="p">,</span>  <span class="c1"># type: bool</span>
        <span class="n">time_start</span><span class="p">,</span>  <span class="c1"># type: Optional[datetime.datetime]</span>
    <span class="p">):</span>
        <span class="c1"># type: (...) -&gt; None</span>

        <span class="n">i_trial</span> <span class="o">=</span> <span class="mi">0</span>

        <span class="k">if</span> <span class="n">time_start</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">time_start</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span>

        <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_stop_flag</span><span class="p">:</span>
                <span class="k">break</span>

            <span class="k">if</span> <span class="n">n_trials</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
                <span class="k">if</span> <span class="n">i_trial</span> <span class="o">&gt;=</span> <span class="n">n_trials</span><span class="p">:</span>
                    <span class="k">break</span>
                <span class="n">i_trial</span> <span class="o">+=</span> <span class="mi">1</span>

            <span class="k">if</span> <span class="n">timeout</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
                <span class="n">elapsed_seconds</span> <span class="o">=</span> <span class="p">(</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span> <span class="o">-</span> <span class="n">time_start</span><span class="p">)</span><span class="o">.</span><span class="n">total_seconds</span><span class="p">()</span>
                <span class="k">if</span> <span class="n">elapsed_seconds</span> <span class="o">&gt;=</span> <span class="n">timeout</span><span class="p">:</span>
                    <span class="k">break</span>

            <span class="bp">self</span><span class="o">.</span><span class="n">_run_trial_and_callbacks</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="n">catch</span><span class="p">,</span> <span class="n">callbacks</span><span class="p">,</span> <span class="n">gc_after_trial</span><span class="p">)</span>

            <span class="bp">self</span><span class="o">.</span><span class="n">_progress_bar</span><span class="o">.</span><span class="n">update</span><span class="p">((</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span> <span class="o">-</span> <span class="n">time_start</span><span class="p">)</span><span class="o">.</span><span class="n">total_seconds</span><span class="p">())</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">remove_session</span><span class="p">()</span>

    <span class="k">def</span> <span class="nf">_pop_waiting_trial_id</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># type: () -&gt; Optional[int]</span>

        <span class="c1"># TODO(c-bata): Reduce database query counts for extracting waiting trials.</span>
        <span class="k">for</span> <span class="n">trial</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">get_all_trials</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">,</span> <span class="n">deepcopy</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
            <span class="k">if</span> <span class="n">trial</span><span class="o">.</span><span class="n">state</span> <span class="o">!=</span> <span class="n">TrialState</span><span class="o">.</span><span class="n">WAITING</span><span class="p">:</span>
                <span class="k">continue</span>

            <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_state</span><span class="p">(</span><span class="n">trial</span><span class="o">.</span><span class="n">_trial_id</span><span class="p">,</span> <span class="n">TrialState</span><span class="o">.</span><span class="n">RUNNING</span><span class="p">):</span>
                <span class="k">continue</span>

            <span class="n">_logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s2">&quot;Trial </span><span class="si">{}</span><span class="s2"> popped from the trial queue.&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">trial</span><span class="o">.</span><span class="n">number</span><span class="p">))</span>
            <span class="k">return</span> <span class="n">trial</span><span class="o">.</span><span class="n">_trial_id</span>

        <span class="k">return</span> <span class="kc">None</span>

    <span class="k">def</span> <span class="nf">_run_trial_and_callbacks</span><span class="p">(</span>
        <span class="bp">self</span><span class="p">,</span>
        <span class="n">func</span><span class="p">,</span>  <span class="c1"># type: ObjectiveFuncType</span>
        <span class="n">catch</span><span class="p">,</span>  <span class="c1"># type: Union[Tuple[()], Tuple[Type[Exception]]]</span>
        <span class="n">callbacks</span><span class="p">,</span>  <span class="c1"># type: Optional[List[Callable[[Study, FrozenTrial], None]]]</span>
        <span class="n">gc_after_trial</span><span class="p">,</span>  <span class="c1"># type: bool</span>
    <span class="p">):</span>
        <span class="c1"># type: (...) -&gt; None</span>

        <span class="n">trial</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_run_trial</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="n">catch</span><span class="p">,</span> <span class="n">gc_after_trial</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">callbacks</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">frozen_trial</span> <span class="o">=</span> <span class="n">copy</span><span class="o">.</span><span class="n">deepcopy</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">get_trial</span><span class="p">(</span><span class="n">trial</span><span class="o">.</span><span class="n">_trial_id</span><span class="p">))</span>
            <span class="k">for</span> <span class="n">callback</span> <span class="ow">in</span> <span class="n">callbacks</span><span class="p">:</span>
                <span class="n">callback</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">frozen_trial</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">_run_trial</span><span class="p">(</span>
        <span class="bp">self</span><span class="p">,</span>
        <span class="n">func</span><span class="p">,</span>  <span class="c1"># type: ObjectiveFuncType</span>
        <span class="n">catch</span><span class="p">,</span>  <span class="c1"># type: Union[Tuple[()], Tuple[Type[Exception]]]</span>
        <span class="n">gc_after_trial</span><span class="p">,</span>  <span class="c1"># type: bool</span>
    <span class="p">):</span>
        <span class="c1"># type: (...) -&gt; trial_module.Trial</span>

        <span class="c1"># Sync storage once at the beginning of the objective evaluation.</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">read_trials_from_remote_storage</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">)</span>

        <span class="n">trial_id</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_pop_waiting_trial_id</span><span class="p">()</span>
        <span class="k">if</span> <span class="n">trial_id</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">trial_id</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">create_new_trial</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_study_id</span><span class="p">)</span>
        <span class="n">trial</span> <span class="o">=</span> <span class="n">trial_module</span><span class="o">.</span><span class="n">Trial</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">trial_id</span><span class="p">)</span>
        <span class="n">trial_number</span> <span class="o">=</span> <span class="n">trial</span><span class="o">.</span><span class="n">number</span>

        <span class="k">try</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">func</span><span class="p">(</span><span class="n">trial</span><span class="p">)</span>
        <span class="k">except</span> <span class="n">exceptions</span><span class="o">.</span><span class="n">TrialPruned</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
            <span class="n">message</span> <span class="o">=</span> <span class="s2">&quot;Trial </span><span class="si">{}</span><span class="s2"> pruned. </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">trial_number</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">))</span>
            <span class="n">_logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>

            <span class="c1"># Register the last intermediate value if present as the value of the trial.</span>
            <span class="c1"># TODO(hvy): Whether a pruned trials should have an actual value can be discussed.</span>
            <span class="n">frozen_trial</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">get_trial</span><span class="p">(</span><span class="n">trial_id</span><span class="p">)</span>
            <span class="n">last_step</span> <span class="o">=</span> <span class="n">frozen_trial</span><span class="o">.</span><span class="n">last_step</span>
            <span class="k">if</span> <span class="n">last_step</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_value</span><span class="p">(</span>
                    <span class="n">trial_id</span><span class="p">,</span> <span class="n">frozen_trial</span><span class="o">.</span><span class="n">intermediate_values</span><span class="p">[</span><span class="n">last_step</span><span class="p">]</span>
                <span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_state</span><span class="p">(</span><span class="n">trial_id</span><span class="p">,</span> <span class="n">TrialState</span><span class="o">.</span><span class="n">PRUNED</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">trial</span>
        <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
            <span class="n">message</span> <span class="o">=</span> <span class="s2">&quot;Trial </span><span class="si">{}</span><span class="s2"> failed because of the following error: </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
                <span class="n">trial_number</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="n">e</span><span class="p">)</span>
            <span class="p">)</span>
            <span class="n">_logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">exc_info</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_system_attr</span><span class="p">(</span><span class="n">trial_id</span><span class="p">,</span> <span class="s2">&quot;fail_reason&quot;</span><span class="p">,</span> <span class="n">message</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_state</span><span class="p">(</span><span class="n">trial_id</span><span class="p">,</span> <span class="n">TrialState</span><span class="o">.</span><span class="n">FAIL</span><span class="p">)</span>

            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">e</span><span class="p">,</span> <span class="n">catch</span><span class="p">):</span>
                <span class="k">return</span> <span class="n">trial</span>
            <span class="k">raise</span>
        <span class="k">finally</span><span class="p">:</span>
            <span class="c1"># The following line mitigates memory problems that can be occurred in some</span>
            <span class="c1"># environments (e.g., services that use computing containers such as CircleCI).</span>
            <span class="c1"># Please refer to the following PR for further details:</span>
            <span class="c1"># https://github.com/optuna/optuna/pull/325.</span>
            <span class="k">if</span> <span class="n">gc_after_trial</span><span class="p">:</span>
                <span class="n">gc</span><span class="o">.</span><span class="n">collect</span><span class="p">()</span>

        <span class="k">try</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="nb">float</span><span class="p">(</span><span class="n">result</span><span class="p">)</span>
        <span class="k">except</span> <span class="p">(</span>
            <span class="ne">ValueError</span><span class="p">,</span>
            <span class="ne">TypeError</span><span class="p">,</span>
        <span class="p">):</span>
            <span class="n">message</span> <span class="o">=</span> <span class="p">(</span>
                <span class="s2">&quot;Trial </span><span class="si">{}</span><span class="s2"> failed, because the returned value from the &quot;</span>
                <span class="s2">&quot;objective function cannot be cast to float. Returned value is: &quot;</span>
                <span class="s2">&quot;</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">trial_number</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="n">result</span><span class="p">))</span>
            <span class="p">)</span>
            <span class="n">_logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_system_attr</span><span class="p">(</span><span class="n">trial_id</span><span class="p">,</span> <span class="s2">&quot;fail_reason&quot;</span><span class="p">,</span> <span class="n">message</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_state</span><span class="p">(</span><span class="n">trial_id</span><span class="p">,</span> <span class="n">TrialState</span><span class="o">.</span><span class="n">FAIL</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">trial</span>

        <span class="k">if</span> <span class="n">math</span><span class="o">.</span><span class="n">isnan</span><span class="p">(</span><span class="n">result</span><span class="p">):</span>
            <span class="n">message</span> <span class="o">=</span> <span class="s2">&quot;Trial </span><span class="si">{}</span><span class="s2"> failed, because the objective function returned </span><span class="si">{}</span><span class="s2">.&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
                <span class="n">trial_number</span><span class="p">,</span> <span class="n">result</span>
            <span class="p">)</span>
            <span class="n">_logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_system_attr</span><span class="p">(</span><span class="n">trial_id</span><span class="p">,</span> <span class="s2">&quot;fail_reason&quot;</span><span class="p">,</span> <span class="n">message</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_state</span><span class="p">(</span><span class="n">trial_id</span><span class="p">,</span> <span class="n">TrialState</span><span class="o">.</span><span class="n">FAIL</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">trial</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_value</span><span class="p">(</span><span class="n">trial_id</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_trial_state</span><span class="p">(</span><span class="n">trial_id</span><span class="p">,</span> <span class="n">TrialState</span><span class="o">.</span><span class="n">COMPLETE</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_log_completed_trial</span><span class="p">(</span><span class="n">trial</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span>

        <span class="k">return</span> <span class="n">trial</span>

    <span class="k">def</span> <span class="nf">_log_completed_trial</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">trial</span><span class="p">,</span> <span class="n">result</span><span class="p">):</span>
        <span class="c1"># type: (trial_module.Trial, float) -&gt; None</span>

        <span class="n">_logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span>
            <span class="s2">&quot;Trial </span><span class="si">{}</span><span class="s2"> finished with value: </span><span class="si">{}</span><span class="s2"> and parameters: </span><span class="si">{}</span><span class="s2">. &quot;</span>
            <span class="s2">&quot;Best is trial </span><span class="si">{}</span><span class="s2"> with value: </span><span class="si">{}</span><span class="s2">.&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
                <span class="n">trial</span><span class="o">.</span><span class="n">number</span><span class="p">,</span> <span class="n">result</span><span class="p">,</span> <span class="n">trial</span><span class="o">.</span><span class="n">params</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">best_trial</span><span class="o">.</span><span class="n">number</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">best_value</span><span class="p">,</span>
            <span class="p">)</span>
        <span class="p">)</span></div>


<div class="viewcode-block" id="create_study"><a class="viewcode-back" href="../../reference/study.html#optuna.create_study">[文档]</a><span class="k">def</span> <span class="nf">create_study</span><span class="p">(</span>
    <span class="n">storage</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Union[None, str, storages.BaseStorage]</span>
    <span class="n">sampler</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: samplers.BaseSampler</span>
    <span class="n">pruner</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: pruners.BasePruner</span>
    <span class="n">study_name</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: Optional[str]</span>
    <span class="n">direction</span><span class="o">=</span><span class="s2">&quot;minimize&quot;</span><span class="p">,</span>  <span class="c1"># type: str</span>
    <span class="n">load_if_exists</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>  <span class="c1"># type: bool</span>
<span class="p">):</span>
    <span class="c1"># type: (...) -&gt; Study</span>
    <span class="sd">&quot;&quot;&quot;Create a new :class:`~optuna.study.Study`.</span>

<span class="sd">    Args:</span>
<span class="sd">        storage:</span>
<span class="sd">            Database URL. If this argument is set to None, in-memory storage is used, and the</span>
<span class="sd">            :class:`~optuna.study.Study` will not be persistent.</span>

<span class="sd">            .. note::</span>
<span class="sd">                When a database URL is passed, Optuna internally uses `SQLAlchemy`_ to handle</span>
<span class="sd">                the database. Please refer to `SQLAlchemy&#39;s document`_ for further details.</span>
<span class="sd">                If you want to specify non-default options to `SQLAlchemy Engine`_, you can</span>
<span class="sd">                instantiate :class:`~optuna.storages.RDBStorage` with your desired options and</span>
<span class="sd">                pass it to the ``storage`` argument instead of a URL.</span>

<span class="sd">             .. _SQLAlchemy: https://www.sqlalchemy.org/</span>
<span class="sd">             .. _SQLAlchemy&#39;s document:</span>
<span class="sd">                 https://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls</span>
<span class="sd">             .. _SQLAlchemy Engine: https://docs.sqlalchemy.org/en/latest/core/engines.html</span>

<span class="sd">        sampler:</span>
<span class="sd">            A sampler object that implements background algorithm for value suggestion.</span>
<span class="sd">            If :obj:`None` is specified, :class:`~optuna.samplers.TPESampler` is used</span>
<span class="sd">            as the default. See also :class:`~optuna.samplers`.</span>
<span class="sd">        pruner:</span>
<span class="sd">            A pruner object that decides early stopping of unpromising trials. See also</span>
<span class="sd">            :class:`~optuna.pruners`.</span>
<span class="sd">        study_name:</span>
<span class="sd">            Study&#39;s name. If this argument is set to None, a unique name is generated</span>
<span class="sd">            automatically.</span>
<span class="sd">        direction:</span>
<span class="sd">            Direction of optimization. Set ``minimize`` for minimization and ``maximize`` for</span>
<span class="sd">            maximization.</span>
<span class="sd">        load_if_exists:</span>
<span class="sd">            Flag to control the behavior to handle a conflict of study names.</span>
<span class="sd">            In the case where a study named ``study_name`` already exists in the ``storage``,</span>
<span class="sd">            a :class:`~optuna.exceptions.DuplicatedStudyError` is raised if ``load_if_exists`` is</span>
<span class="sd">            set to :obj:`False`.</span>
<span class="sd">            Otherwise, the creation of the study is skipped, and the existing one is returned.</span>

<span class="sd">    Returns:</span>
<span class="sd">        A :class:`~optuna.study.Study` object.</span>

<span class="sd">    &quot;&quot;&quot;</span>

    <span class="n">storage</span> <span class="o">=</span> <span class="n">storages</span><span class="o">.</span><span class="n">get_storage</span><span class="p">(</span><span class="n">storage</span><span class="p">)</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="n">study_id</span> <span class="o">=</span> <span class="n">storage</span><span class="o">.</span><span class="n">create_new_study</span><span class="p">(</span><span class="n">study_name</span><span class="p">)</span>
    <span class="k">except</span> <span class="n">exceptions</span><span class="o">.</span><span class="n">DuplicatedStudyError</span><span class="p">:</span>
        <span class="k">if</span> <span class="n">load_if_exists</span><span class="p">:</span>
            <span class="k">assert</span> <span class="n">study_name</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>

            <span class="n">_logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span>
                <span class="s2">&quot;Using an existing study with name &#39;</span><span class="si">{}</span><span class="s2">&#39; instead of &quot;</span>
                <span class="s2">&quot;creating a new one.&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">study_name</span><span class="p">)</span>
            <span class="p">)</span>
            <span class="n">study_id</span> <span class="o">=</span> <span class="n">storage</span><span class="o">.</span><span class="n">get_study_id_from_name</span><span class="p">(</span><span class="n">study_name</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">raise</span>

    <span class="n">study_name</span> <span class="o">=</span> <span class="n">storage</span><span class="o">.</span><span class="n">get_study_name_from_id</span><span class="p">(</span><span class="n">study_id</span><span class="p">)</span>
    <span class="n">study</span> <span class="o">=</span> <span class="n">Study</span><span class="p">(</span><span class="n">study_name</span><span class="o">=</span><span class="n">study_name</span><span class="p">,</span> <span class="n">storage</span><span class="o">=</span><span class="n">storage</span><span class="p">,</span> <span class="n">sampler</span><span class="o">=</span><span class="n">sampler</span><span class="p">,</span> <span class="n">pruner</span><span class="o">=</span><span class="n">pruner</span><span class="p">)</span>

    <span class="k">if</span> <span class="n">direction</span> <span class="o">==</span> <span class="s2">&quot;minimize&quot;</span><span class="p">:</span>
        <span class="n">_direction</span> <span class="o">=</span> <span class="n">StudyDirection</span><span class="o">.</span><span class="n">MINIMIZE</span>
    <span class="k">elif</span> <span class="n">direction</span> <span class="o">==</span> <span class="s2">&quot;maximize&quot;</span><span class="p">:</span>
        <span class="n">_direction</span> <span class="o">=</span> <span class="n">StudyDirection</span><span class="o">.</span><span class="n">MAXIMIZE</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Please set either &#39;minimize&#39; or &#39;maximize&#39; to direction.&quot;</span><span class="p">)</span>

    <span class="n">study</span><span class="o">.</span><span class="n">_storage</span><span class="o">.</span><span class="n">set_study_direction</span><span class="p">(</span><span class="n">study_id</span><span class="p">,</span> <span class="n">_direction</span><span class="p">)</span>

    <span class="k">return</span> <span class="n">study</span></div>


<div class="viewcode-block" id="load_study"><a class="viewcode-back" href="../../reference/study.html#optuna.load_study">[文档]</a><span class="k">def</span> <span class="nf">load_study</span><span class="p">(</span>
    <span class="n">study_name</span><span class="p">,</span>  <span class="c1"># type: str</span>
    <span class="n">storage</span><span class="p">,</span>  <span class="c1"># type: Union[str, storages.BaseStorage]</span>
    <span class="n">sampler</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: samplers.BaseSampler</span>
    <span class="n">pruner</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># type: pruners.BasePruner</span>
<span class="p">):</span>
    <span class="c1"># type: (...) -&gt; Study</span>
    <span class="sd">&quot;&quot;&quot;Load the existing :class:`~optuna.study.Study` that has the specified name.</span>

<span class="sd">    Args:</span>
<span class="sd">        study_name:</span>
<span class="sd">            Study&#39;s name. Each study has a unique name as an identifier.</span>
<span class="sd">        storage:</span>
<span class="sd">            Database URL such as ``sqlite:///example.db``. Please see also the documentation of</span>
<span class="sd">            :func:`~optuna.study.create_study` for further details.</span>
<span class="sd">        sampler:</span>
<span class="sd">            A sampler object that implements background algorithm for value suggestion.</span>
<span class="sd">            If :obj:`None` is specified, :class:`~optuna.samplers.TPESampler` is used</span>
<span class="sd">            as the default. See also :class:`~optuna.samplers`.</span>
<span class="sd">        pruner:</span>
<span class="sd">            A pruner object that decides early stopping of unpromising trials.</span>
<span class="sd">            If :obj:`None` is specified, :class:`~optuna.pruners.MedianPruner` is used</span>
<span class="sd">            as the default. See also :class:`~optuna.pruners`.</span>

<span class="sd">    &quot;&quot;&quot;</span>

    <span class="k">return</span> <span class="n">Study</span><span class="p">(</span><span class="n">study_name</span><span class="o">=</span><span class="n">study_name</span><span class="p">,</span> <span class="n">storage</span><span class="o">=</span><span class="n">storage</span><span class="p">,</span> <span class="n">sampler</span><span class="o">=</span><span class="n">sampler</span><span class="p">,</span> <span class="n">pruner</span><span class="o">=</span><span class="n">pruner</span><span class="p">)</span></div>


<div class="viewcode-block" id="delete_study"><a class="viewcode-back" href="../../reference/study.html#optuna.delete_study">[文档]</a><span class="k">def</span> <span class="nf">delete_study</span><span class="p">(</span>
    <span class="n">study_name</span><span class="p">,</span>  <span class="c1"># type: str</span>
    <span class="n">storage</span><span class="p">,</span>  <span class="c1"># type: Union[str, storages.BaseStorage]</span>
<span class="p">):</span>
    <span class="c1"># type: (...) -&gt; None</span>
    <span class="sd">&quot;&quot;&quot;Delete a :class:`~optuna.study.Study` object.</span>

<span class="sd">    Args:</span>
<span class="sd">        study_name:</span>
<span class="sd">            Study&#39;s name.</span>
<span class="sd">        storage:</span>
<span class="sd">            Database URL such as ``sqlite:///example.db``. Please see also the documentation of</span>
<span class="sd">            :func:`~optuna.study.create_study` for further details.</span>

<span class="sd">    &quot;&quot;&quot;</span>

    <span class="n">storage</span> <span class="o">=</span> <span class="n">storages</span><span class="o">.</span><span class="n">get_storage</span><span class="p">(</span><span class="n">storage</span><span class="p">)</span>
    <span class="n">study_id</span> <span class="o">=</span> <span class="n">storage</span><span class="o">.</span><span class="n">get_study_id_from_name</span><span class="p">(</span><span class="n">study_name</span><span class="p">)</span>
    <span class="n">storage</span><span class="o">.</span><span class="n">delete_study</span><span class="p">(</span><span class="n">study_id</span><span class="p">)</span></div>


<div class="viewcode-block" id="get_all_study_summaries"><a class="viewcode-back" href="../../reference/study.html#optuna.get_all_study_summaries">[文档]</a><span class="k">def</span> <span class="nf">get_all_study_summaries</span><span class="p">(</span><span class="n">storage</span><span class="p">):</span>
    <span class="c1"># type: (Union[str, storages.BaseStorage]) -&gt; List[StudySummary]</span>
    <span class="sd">&quot;&quot;&quot;Get all history of studies stored in a specified storage.</span>

<span class="sd">    Args:</span>
<span class="sd">        storage:</span>
<span class="sd">            Database URL such as ``sqlite:///example.db``. Please see also the documentation of</span>
<span class="sd">            :func:`~optuna.study.create_study` for further details.</span>

<span class="sd">    Returns:</span>
<span class="sd">        List of study history summarized as :class:`~optuna.study.StudySummary` objects.</span>

<span class="sd">    &quot;&quot;&quot;</span>

    <span class="n">storage</span> <span class="o">=</span> <span class="n">storages</span><span class="o">.</span><span class="n">get_storage</span><span class="p">(</span><span class="n">storage</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">storage</span><span class="o">.</span><span class="n">get_all_study_summaries</span><span class="p">()</span></div>
</pre></div>

           </div>
           
          </div>
          <footer>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2018, Optuna Contributors.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
    <a href="../../privacy.html">Privacy Policy</a>.
     


</footer>

        </div>
      </div>

    </section>

  </div>
  


  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
    <!-- Theme Analytics -->
    <script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

    ga('create', 'UA-55135190-8', 'auto');
    ga('send', 'pageview');
    </script>

    
   

</body>
</html>